@mapbox/tiny-sdf

What is @mapbox/tiny-sdf?

@mapbox/tiny-sdf is a JavaScript library that generates tiny signed distance fields (SDF) for text rendering. It is particularly useful for rendering high-quality text in WebGL contexts, such as in maps or other graphics applications where text clarity and performance are important.

What are @mapbox/tiny-sdf's main functionalities?

Generate SDF for a single character

This feature allows you to generate a signed distance field for a single character. The `draw` method takes a character as input and returns a grayscale image representing the SDF.

const TinySDF = require('@mapbox/tiny-sdf');
const tinySDF = new TinySDF();
const sdf = tinySDF.draw('A');
console.log(sdf);

Customizing SDF parameters

You can customize the parameters of the SDF generation, such as the font size, buffer, radius, cutoff, and font family. This allows for greater control over the appearance and quality of the generated SDF.

const TinySDF = require('@mapbox/tiny-sdf');
const tinySDF = new TinySDF(24, 3, 8, 72, 'serif');
const sdf = tinySDF.draw('B');
console.log(sdf);

Rendering text with SDF in WebGL

This feature demonstrates how to use the generated SDF texture in a WebGL context. The SDF can be used as a texture in WebGL to render high-quality text with smooth edges.

const TinySDF = require('@mapbox/tiny-sdf');
const tinySDF = new TinySDF();
const sdf = tinySDF.draw('C');
// Use the SDF texture in a WebGL context
const texture = gl.createTexture();
gl.bindTexture(gl.TEXTURE_2D, texture);
gl.texImage2D(gl.TEXTURE_2D, 0, gl.ALPHA, tinySDF.size, tinySDF.size, 0, gl.ALPHA, gl.UNSIGNED_BYTE, sdf);

Other packages similar to @mapbox/tiny-sdf

opentype.js

opentype.js is a JavaScript library for parsing and working with OpenType fonts. While it does not generate SDFs directly, it can be used in conjunction with other libraries to extract font glyphs and generate SDFs from them.

README

TinySDF

TinySDF is a tiny and fast JavaScript library for generating SDF (signed distance field) from system fonts on the browser using Canvas 2D and Felzenszwalb/Huttenlocher distance transform. This is very useful for rendering text with WebGL.

Demo

Usage

Create a TinySDF for drawing glyph SDFs based on font parameters:

const tinySdf = new TinySDF({
    fontSize: 24,             // Font size in pixels
    fontFamily: 'sans-serif', // CSS font-family
    fontWeight: 'normal',     // CSS font-weight
    fontStyle: 'normal',      // CSS font-style
    buffer: 3,                // Whitespace buffer around a glyph in pixels
    radius: 8,                // How many pixels around the glyph shape to use for encoding distance
    cutoff: 0.25              // How much of the radius (relative) is used for the inside part of the glyph
});

const glyph = tinySdf.draw('泽'); // draw a single character

Returns an object with the following properties:

• data is a Uint8ClampedArray array of alpha values (0–255) for a width x height grid.
• width: Width of the returned bitmap.
• height: Height of the returned bitmap.
• glyphTop: Maximum ascent of the glyph from alphabetic baseline.
• glyphLeft: Currently hardwired to 0 (actual glyph differences are encoded in the rasterization).
• glyphWidth: Width of the rasterized portion of the glyph.
• glyphHeight Height of the rasterized portion of the glyph.
• glyphAdvance: Layout advance.

TinySDF is provided as a ES module, so it's only supported on modern browsers, excluding IE.

<script type="module">
import TinySDF from 'https://cdn.skypack.dev/@mapbox/tiny-sdf';
...
</script>

In Node, you can't use require — only import in ESM-capable versions (v12.15+):

import TinySDF from '@mapbox/tiny-sdf';

Development

npm test  # run tests
npm start # start server for the demo page

License

This implementation is licensed under the BSD 2-Clause license. It's based directly on the algorithm published in the Felzenszwalb/Huttenlocher paper, and is not a port of the existing C++ implementation provided by the paper's authors.